{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Including citations in your book\n",
    "\n",
    "✨**experimental**✨"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Because `jupyter-book` is built on top of Jekyll, we can use the excellent\n",
    "[jekyll-scholar](https://github.com/inukshuk/jekyll-scholar) book to\n",
    "include citations and a bibliography with your book.\n",
    "\n",
    "**Note that this only works if you're building your book HTML locally and\n",
    "hosting the HTML files online somewhere**. This can still use GitHub pages, but\n",
    "not the auto-generation of a cite from markdown files feature of GitHub pages.\n",
    "This is because GitHub pages doesn't include the `jekyll-scholar` plugin.\n",
    "\n",
    "## How to use citations\n",
    "\n",
    "Including citations with your markdown files or notebooks is done in the following\n",
    "way.\n",
    "\n",
    "1. Modify the file in `_bibliography/references.bib`. This has a few sample citations\n",
    "in bibtex form. Update as you wish!\n",
    "2. In your content, add the following text to include a citation\n",
    "   \n",
    "   ```\n",
    "   {% raw %}{% cite bibtex_shortname %}{% endraw %}\n",
    "   ```\n",
    "   \n",
    "   For example, this text: `{% raw %}{% cite holdgraf_evidence_2014 %}{% endraw %}` generates this citation: {% cite holdgraf_evidence_2014 %}\n",
    "   \n",
    "   You can also include multiple citations in one go, like so:\n",
    "   \n",
    "   `{% raw %}{% cite holdgraf_evidence_2014 holdgraf_portable_2017 ruby %}{% endraw %}` becomes {% cite holdgraf_evidence_2014 holdgraf_portable_2017 ruby %}\n",
    "   \n",
    "3. Generate a bibliography on your page by using the following text:\n",
    "\n",
    "   ```\n",
    "   {% raw %}{% bibliography %}{% endraw %}\n",
    "   ```\n",
    "   \n",
    "   This will generate a bibliography for your entire bibtex file. If you'd like to restrict teh\n",
    "   bibliography to only the citations you've used on a page, use the following syntax:\n",
    "   \n",
    "   ```\n",
    "   {% raw %}{% bibliography --cited %}{% endraw %}\n",
    "   ```\n",
    "   \n",
    "When your book is built, the bibliography and citations will now be included. For example,\n",
    "see the Bibliography generated below!\n",
    "\n",
    "## References\n",
    "\n",
    "{% bibliography --cited %}"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "jupytext": {
   "formats": "ipynb,md"
  },
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.3"
  },
  "widgets": {
   "application/vnd.jupyter.widget-state+json": {
    "state": {},
    "version_major": 2,
    "version_minor": 0
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}
